Skip to main content

Digital World – Asset QR Payment & Distributor Linking

1. System Overview​

The QR Payment flow involves:

  • Web Dashboard (Asset Page)
  • Backend API
  • Mobile Wallet Application
  • CLEAR payment network
  • Asset Database
  • Blockchain queue system

The process completes when:

  1. QR code is generated
  2. Wallet scans QR
  3. Wallet makes CLEAR payment
  4. Backend detects payment
  5. Distributor public key is assigned
  6. Asset is generated (if required)

2. High-Level Flow Summary​

  • Step 1 → Generate Asset QR
  • Step 2 → Wallet scans QR
  • Step 3 → Wallet sends CLEAR payment
  • Step 4 → Backend checks payment
  • Step 5 → Distributor key linked
  • Step 6 → Asset generated (if ClearPAY source)
  • Step 7 → Success response returned

3. QR Code Generation​

Endpoint GET /rest/dashboard/organizations/{organization_id}/assets/{asset_id}/qrcode

Purpose Generates a QR string containing all asset payment data.

Backend Method getAssetQrCode($organization_id, $asset_id)

QR Code Data Structure The QR string contains: CLEAR_ACCOUNT | issuer_public_key | asset_ticker | organization_name | quantity_issued | quantity_authorized | asset_id | locked_flag | toml_domain

Field Definitions

  • CLEAR_ACCOUNT → Payment receiving account
  • issuer_public_key → Asset issuer
  • asset_ticker → Asset symbol
  • organization_name → URL encoded name
  • quantity_issued → Issued amount
  • quantity_authorized → Authorized amount
  • asset_id → Internal reference
  • locked_flag → TRUE/FALSE (issuer source logic)
  • toml_domain → Asset metadata domain

4. Mobile Wallet Behavior​

After scanning QR:

  1. Wallet parses QR string
  2. Wallet prepares CLEAR payment

Payment is sent from:

  • from_account (Distributor wallet)
  • To CLEAR_ACCOUNT

Once payment is submitted:

  • Transaction is broadcast to network
  • Blockchain confirms payment

5. Payment Detection Endpoint​

Endpoint GET /rest/dashboard/organizations/{organization_id}/assets/{asset_id}/check_payment

Backend Method checkQRPayment($organization_id, $asset_id)

Purpose Checks whether a valid payment has been received for the asset.

6. Payment Processing Logic​

When check_payment runs:

Step 1 – Validate Asset​

  • Confirm organization exists
  • Confirm asset exists

Step 2 – Check Payment​

System checks: clearPayments->checkPaymentReceivedForNewTokenByAssetId($asset_id)

If payment found:

Step 3 – Distributor Assignment​

If distributor_public_key is empty: setDistributorPublicKey(asset_id, payment->from_account)

Distributor public key becomes: payment->from_account

Response:

{
  "success": true,
  "message": "Distributor key linked"
}

7. Asset Generation Logic​

If: asset->issuer_source == "ClearPAY"

Then:

  • Asset marked as generated
  • Status updated

Response message: Asset Generated successfully!

Returned data:

  • issuer_public_key
  • distributor_public_key

8. Duplicate & Edge Conditions​

Case 1 – Already Generated → Response: Assets already generated

Case 2 – Distributor Already Linked → Returns: Distributor key linked

Case 3 – Wrong Asset ID → Returns: Wrong Organization or Asset ID

9. Background Queue​

After payment detection: generateQueue($asset_id)

This pushes asset into processing pipeline for:

  • Digital World queue
  • Blockchain issuance
  • Further automation

10. JSON Response Structure​

Standard Response:

{
  "success": boolean,
  "message": string,
  "data": {
      "issuer_public_key": "...",
      "distributor_public_key": "..."
  }
}

This makes it AI-readable and automation-compatible.

11. AI Agent Compatibility​

An AI agent can:

  • Call QR endpoint
  • Extract QR payload
  • Simulate payment from wallet
  • Call check_payment endpoint
  • Detect distributor assignment
  • Verify asset generation state

All logic is machine-readable and state-driven.

12. Testing Scenarios​

Test 1 – Successful Payment

  • Generate QR
  • Simulate CLEAR payment
  • Call check_payment
  • Confirm distributor_public_key updated
  • Confirm success message

Test 2 – Duplicate Payment

  • Run check_payment again
  • Confirm "Distributor key linked" OR "Assets already generated"

Test 3 – Invalid Asset

  • Call with wrong ID
  • Confirm failure response

13. Security & Validation​

  • Payment must originate from valid CLEAR account
  • Distributor key is derived from payment sender
  • Asset cannot be generated twice
  • Asset state is validated before modification

14. Final State Summary​

Before Payment:

  • distributor_public_key = null
  • is_asset_generated = No

After Payment:

  • distributor_public_key = wallet public key
  • is_asset_generated = Yes (if ClearPAY source)

System ensures:

  • One-time generation
  • Verified payment-based linking
  • Blockchain-safe issuance